package de.zainodis.commons.xml;

import org.xmlpull.v1.XmlPullParser;

public interface IParser<T> {

   /**
    * Parses xml using the given {@link XmlPullParser}. The parser will be at a
    * certain location so be sure you know at which location in the XML document
    * you expect the parser to be.
    * 
    * @param parser
    *           the parser containing the xml content.
    */
   T parse(XmlPullParser parser) throws ParseException;

   /**
    * Get next parsing event - element content will be coalesced(collapsed) and
    * only one TEXT event must be returned for whole element content (comments
    * and processing instructions will be ignored and entity references must be
    * expanded or exceptions must be thrown if an entity reference can not be
    * expanded). If the element content is empty (content is "") then no TEXT
    * event will be reported. NOTE: empty element (such as <tag/>) will be
    * reported with two separate events: START_TAG, END_TAG - this is required
    * to preserve parsing consistency of empty elements such as <tag/> and
    * non-empty elements such as <tag></tag>). Advances the parser to the next
    * element if isDone is false. If isDone is true however, -1 is returned to
    * signal that the parser has completed.
    * 
    */
   int next(boolean isDone, XmlPullParser parser) throws ParseException;

}
